Rem  Copyright (c) 1999, 2000 by Marcelo F. Ochoa.  All Rights Reserved.
Rem
Rem   NAME
Rem     xtp.spc - DB Prism Xml Toolkit Procedures (xtp)
Rem   PURPOSE
Rem     Install the PL/SQL needed to run the XML Application.
Rem   NOTES
Rem
Rem   HISTORY
Rem     mochoa@ieee.org   04/02/02 -
Rem       add comment procedure
Rem     mochoa@ieee.org   07/02/02 -
Rem   Tags for Cocoon2 architecture and DBPrismGenerator
Rem     mochoa@ieee.org   11/17/00 -
Rem		replace xtp.tag(cname,cvalue,bclose)
Rem		by xtp.tag(cname,cvalue,cattributes)
Rem		correct syntax of xtp.send according to a new format of date
Rem		in HeaderProcessor class
Rem     mochoa@ieee.org   1/7/00 -  Creation version 1.0.0
Rem

CREATE OR REPLACE PACKAGE xtp AS

contentType VARCHAR2(256) := 'text/xml';

-- version 2.0.0
----------------------------------------------
-- REQUIRES HTP TOOLKITS of 8.1.7+ installed -
-- by default it is installed on sys schema --
----------------------------------------------
-- obsoletes procedures:
--   xtp.prolog(cversion,cstylesheet,cmedia,cattrbutes) replaced by xtp.prolog(cversion)
--   xtp.stylesheet(...)
--   xtp.process(...)
--   xtp.not_found
-- new procedures:
--   xtp.comment(ccomment)
--   xtp.header(cContentType,bCloseHeader)
--   xtp.setEncoding(cEncoding)
--   xtp.setContentType(cContentType)
--   xtp.setHeader(cName,cValue)
--   xtp.closeHeader
-- new attributes
--   contentType
----------------------------------------------
-- version 1.0.1
--   replaced xtp.tag(cname,cvalue,bclose)
--   by xtp.tag(cname,cvalue,cattributes)
--   correct syntax of xtp.send according to a new format of date in HeaderProcessor class
--
----------------------------------------------
-- version 1.0.0
--   initial

procedure prolog(cversion in VARCHAR2 default '1.0');
procedure comment(ccomment in VARCHAR2);
procedure epilog;
procedure tag(cname in VARCHAR2,
		cvalue in VARCHAR2,
		cattributes  in VARCHAR2 default NULL);
procedure tagOpen(cname in VARCHAR2, cattributes in VARCHAR2 default NULL);
procedure tagClose(cname in VARCHAR2);

/* SPECIAL PROCEDURES */
  -- Output Procedures
procedure print (cbuf in varchar2 DEFAULT NULL);
procedure print (dbuf in date);
procedure print (nbuf in number);

  -- Output without the newline
procedure prn (cbuf in varchar2 DEFAULT NULL);
procedure prn (dbuf in date);
procedure prn (nbuf in number);

  -- Abbrev call to print()
procedure p (cbuf in varchar2 DEFAULT NULL);
procedure p (dbuf in date);
procedure p (nbuf in number);

procedure prints(ctext in varchar2);
procedure ps(ctext in varchar2);
procedure escape_sc(ctext in varchar2);
/* END SPECIAL PROCEDURES */

/* REDIRECT_URL will output "Location: <curl>\n\n"               */
/* This allows the PL/SQL program to tell the HTTP server to     */
/* visit the specified URL instead of returning output from the  */
/* current URL.  By "visit" it is meant that if the specified    */
/* URL is an HTML page, then it will be returned, but if the URL */
/* specifies another CGI program, or call to the Web Agent, then */
/* the Web Server will make that call.                           */
/* The call to REDIRECT_URL MUST be come before any xtp calls in */
/* order to signal the HTTP server to do the redirect.           */
/* This functionality is only available with OWA 1.0.2 or above. */
procedure redirect_url(curl in varchar2);

-- NOT_AUTHORIZED force to user to entry new user/password for an Realm                                          
procedure not_authorized(realm in varchar2);

-- New Procedures in version 2.0.0
procedure header(cContentType in varchar2, bCloseHeader boolean default true);
procedure setEncoding(cEncoding in varchar2);
procedure setContentType(cContentType in varchar2);
procedure setHeader(cName in varchar2, cValue in varchar2);
procedure closeHeader;

-- These procedures/functions are merely wrappers around
-- calls to send an owa_cookie and to get an owa_cookie.
-- One should be familiar with the specification for
-- HTTP cookies before attempting to use these subprograms.

-- Calls to the procedure SEND generate an HTTP header line
-- of the form:
-- Set-Cookie: <name>=<value> expires=<expires> path=<path>
--             domain=<domain> [secure]
-- Only the name and value are required (as per the owa_cookie spec),
-- and the default is non-secure.
-- Calls to SEND must fall in the context of an OWA procedure's
-- HTTP header output.  For example:

-- begin
--    xtp.send('ITEM1','SOCKS');
--    xtp.send('ITEM2','SHOES');
--
--    -- Now output the page the user will see.
--    xtp.Prolog;
--    <etc>
procedure send(name    in varchar2,
               value   in varchar2,
               expires in date     DEFAULT NULL,
               path    in varchar2 DEFAULT NULL,
               domain  in varchar2 DEFAULT NULL,
               secure  in varchar2 DEFAULT NULL);

-- GET will return an owa_cookie.COOKIE structure
-- for the specified cookie name.
function get(name in varchar2) return owa_cookie.cookie;

-- REMOVE will simply force the expiration of an existing cookie.
-- This call must come within the context of an HTTP header.
-- See the definition of SEND above.
-- REMOVE generates a line which looks like:
-- Set-Cookie: <name>=<value> expires=01-JAN-1990
procedure remove(name in varchar2,
                 val  in varchar2,
                 path in varchar2 DEFAULT NULL);

-- GET_ALL returns an array of name/value pairs of all HTTP_COOKIES
-- sent from the browser.  The name/value pairs appear in the order
-- that they were sent from the browser.
procedure get_all(names    out owa_cookie.vc_arr,
                  vals     out owa_cookie.vc_arr,
                  num_vals out integer);
END xtp;
/
